<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer&#39;s Guide: &lt;code&gt;Application.mk&lt;/code&gt;</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">NDK Programmer&#39;s Guide
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__building__a_p_p_l_i_c_a_t_i_o_n-_m_k.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title"><code>Application.mk</code> </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2>Introduction</h2>
<p>This document describes the syntax of <code>Application.mk</code> build file written to describe the native modules required by your Android application. To understand what follows, it is assumed that you have read the <a href="md_1__concepts__concepts.html">Concepts</a> and <a href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk</a> sections of this document.</p>
<h2>Overview</h2>
<p>The purpose of <code>Application.mk</code> is to describe which native 'modules' (i.e. static/shared libraries) are needed by your application.</p>
<p>An <code>Application.mk</code> file is usually placed under <code>$PROJECT/jni/Application.mk</code>, where <code>$PROJECT</code> points to your application's project directory.</p>
<p>Another alternative is to place it under a sub-directory of the top-level <code>$NDK/apps</code> directory, e.g.: </p>
<pre class="fragment">      $NDK/apps/&lt;myapp&gt;/`Application.mk`
</pre><p>Where &lt;myapp&gt; is a short name used to describe your 'application' to the NDK build system (this name doesn't go into your generated shared libraries or your final packages).</p>
<p>The <code>Application.mk</code> is really a tiny GNU Makefile fragment that must define a few variables:</p>
<h3><code>APP_PROJECT_PATH</code></h3>
<p>This variable should give the <em>absolute</em> path to your Application's project root directory. This is used to copy/install stripped versions of the generated JNI shared libraries to a specific location known to the APK-generating tools.</p>
<p>Note that it is optional for <code>$PROJECT/jni/Application.mk</code>, but <em>mandatory</em> for <code>$NDK/apps/&lt;myapp/Application.mk</code></p>
<h3><code>APP_MODULES</code></h3>
<p>If this variable is defined, it tells <code>ndk-build</code> to only list the corresponding modules and those that they depend on. It must be a space-separated list of module names as they appear in the LOCAL_MODULE definition of Android.mk files.</p>
<p>It the variable is undefined, <code>ndk-build</code> looks for the list of all <em>installable</em> top-level modules, i.e. those listed by your Android.mk and any file it includes directly. Imported modules are <em>not</em> top-level though.</p>
<p>An installable module is either a shared library or executable, which will generate a file in <code>libs/$ABI/</code>.</p>
<p>If the variable is undefined, and there are no installable top-level modules in your project, then <code>ndk-build</code> will build all top-level static libraries and their dependencies instead. However, these libraries will be placed at the usual location under <code>obj/</code> or <code>obj-debug/</code>.</p>
<p>NOTE: This variable's behaviour changed in NDK r4. Before that:</p>
<ul>
<li>the variable was mandatory in your <code>Application.mk</code></li>
<li>all required modules had to be listed explicitly.</li>
</ul>
<h3><code>APP_OPTIM</code></h3>
<p>This optional variable can be defined to either '<code>release</code>' or '<code>debug</code>'. This is used to alter the optimization level when building your application's modules.</p>
<p>A 'release' mode is the default, and will generate highly optimized binaries. The 'debug' mode will generate un-optimized binaries which are much easier to debug.</p>
<p>Note that if your application is debuggable (i.e. if your manifest sets the <code>android:debuggable</code> attribute to "`true`" in its <code>&lt;application&gt;</code> tag), the default will be 'debug' instead of 'release'. This can be overridden by setting APP_OPTIM to '<code>release</code>'.</p>
<p>Note that it is possible to debug both 'release' and 'debug' binaries, but the 'release' builds tend to provide less information during debugging sessions: some variables are optimized out and can't be inspected, code re-ordering can make stepping through the code difficult, stack traces may not be reliable, etc...</p>
<h3><code>APP_CFLAGS</code></h3>
<p>A set of C compiler flags passed when compiling any C or C++ source code of any of the modules. This can be used to change the build of a given module depending on the application that needs it, instead of modifying the Android.mk file itself. </p>
<pre class="fragment">    IMPORTANT WARNING: +++++++++++++++++++++++++++++++++++++++++++++++++++
    +
    + All paths in these flags should be relative to the top-level NDK
    + directory. For example, if you have the following setup:
    +
    +    sources/foo/Android.mk
    +    sources/bar/Android.mk
    +
    +  To specify in foo/Android.mk that you want to add the path to the
    + 'bar' sources during compilation, you should use:
    +
    +   APP_CFLAGS += -Isources/bar
    +
    + Or alternatively:
    +
    +   APP_CFLAGS += -I$(LOCAL_PATH)/../bar
    +
    + Using '-I../bar' will *NOT* work since it will be equivalent to
    + '-I$NDK_ROOT/../bar' instead.
    +
    +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
</pre><p>NOTE: In android-ndk-1.5_r1, this only applied to C sources, not C++ ones. This has been corrected to match the full Android build system.</p>
<h3><code>APP_CXXFLAGS</code></h3>
<p>An alias for APP_CPPFLAGS, to be considered obsolete as it may disappear in a future release of the NDK.</p>
<h3><code>APP_CPPFLAGS</code></h3>
<p>A set of C++ compiler flags passed when building C++ sources <em>only</em>.</p>
<p>NOTE: In android-ndk-1.5_r1, this applied to both C and C++ sources. This has been corrected to match the full Android build system. You can now use APP_CFLAGS for flags that shall apply to C and C++ sources.</p>
<h3><code>APP_LDFLAGS</code></h3>
<p>A set of linker flags passed when linking application. This only applies when building shared libraries and executables, these flags are ignored when building static libraries.</p>
<h3><code>APP_BUILD_SCRIPT</code></h3>
<p>By default, the NDK build system will look for a file named Android.mk under <code>/jni</code>, i.e. for the file: </p>
<pre class="fragment">        $(APP_PROJECT_PATH)/jni/Android.mk
</pre><p>If you want to override this behaviour, you can define APP_BUILD_SCRIPT to point to an alternate build script. A non-absolute path will always be interpreted as relative to the NDK's top-level directory.</p>
<h3><code>APP_ABI</code></h3>
<p>By default, the NDK build system will generate machine code for the '<code>armeabi</code>' ABI. This corresponds to an ARMv5TE based CPU with software floating point operations. You can use APP_ABI to select a different ABI.</p>
<p>For example, to support hardware FPU instructions on ARMv7 based devices, use: </p>
<pre class="fragment">          APP_ABI := armeabi-v7a
</pre><p>Or to support ARMv8 AArch64 instruction set, use: </p>
<pre class="fragment">          APP_ABI := arm64-v8a
</pre><p>Or to support the IA-32 instruction set, use: </p>
<pre class="fragment">          APP_ABI := x86
</pre><p>Or to support the Intel64 instruction set (r1), use: </p>
<pre class="fragment">          APP_ABI := x86_64
</pre><p>Or to support the MIPS32 instruction set, use: </p>
<pre class="fragment">          APP_ABI := mips
</pre><p>Or to support the MIPS64 instruction set (r6), use: </p>
<pre class="fragment">          APP_ABI := mips64
</pre><p>Or to support all at the same time, use: </p>
<pre class="fragment">          APP_ABI := armeabi armeabi-v7a x86 mips arm64-v8a x86_64 mips64
</pre><p>Or even better, since NDK r7, you can also use the special value '<code>all</code>' which means "all ABIs supported by this NDK release": </p>
<pre class="fragment">          APP_ABI := all
</pre><p>For the list of all supported ABIs and details about their usage and limitations, refer to the <a href="./md_3__key__topics__c_p_u__support__chapter_1-section_8__a_b_is.html">Android Native CPU ABI Management</a> section.</p>
<h3><code>APP_PLATFORM</code></h3>
<p>Name the target Android platform. For example, '<code>android-3</code>' correspond to Android 1.5 system images. For a complete list of platform names and corresponding Android system images, see the <a href="file:///usr/local/google/internal-master/master/ndk/docs/Programmers_Guide/html/./md_3__key__topics__libraries__s_t_a_b_l_e-_a_p_i_s.html">Android NDK Stable APIs</a> section.</p>
<h3><code>APP_STL</code></h3>
<p>By default, the NDK build system provides C++ headers for the minimal C++ runtime library (<code>/system/lib/libstdc++.so</code>) provided by the Android system.</p>
<p>However, the NDK comes with alternative C++ implementations that you can use or link to in your own applications. Define APP_STL to select one of them. Examples are: </p>
<pre class="fragment">        APP_STL := stlport_static    --&gt; static STLport library
        APP_STL := stlport_shared    --&gt; shared STLport library
        APP_STL := system            --&gt; default C++ runtime library
</pre><p>For more information on this subject, see the <a href="./md_3__key__topics__libraries__c_p_l_u_s_p_l_u_s-_s_u_p_p_o_r_t.html">C++ Support</a> section.</p>
<h3><code>APP_GNUSTL_FORCE_CPP_FEATURES</code></h3>
<p>In prior NDK versions, the simple fact of using the GNU libstdc++ runtime (i.e. by setting APP_STL to either '<code>gnustl_static</code>' or '<code>gnustl_shared</code>') enforced the support for exceptions and RTTI in all generated machine code. This could be problematic in specific, but rare, cases, and also generated un-necessarily bigger code for projects that don't require these features.</p>
<p>This bug was fixed in NDK r7b, but this means that if your code requires exceptions or RTTI, it should now explicitly say so, either in your APP_CPPFLAGS, or your LOCAL_CPPFLAGS / LOCAL_CPP_FEATURES definitions.</p>
<p>To make it easier to port projects to NDK r7b and later, one can optionally defined APP_GNUSTL_CPP_FEATURES to contain one or more of the following values: </p>
<pre class="fragment">        exceptions    -&gt; to enforce exceptions support for all modules.
        rtti          -&gt; to enforce rtti support for all modules.
</pre><p>For example, to get the exact same behaviour than NDK r7: </p>
<pre class="fragment">        APP_GNUSTL_FORCE_CPP_FEATURES := exceptions rtti
</pre><p>IMPORTANT: This variable is provided here as a convenience to make it easier to transition to a newer version of the NDK. It will be removed in a future revision. We thus encourage all developers to modify the module definitions properly instead of relying on it here.</p>
<h3><code>APP_SHORT_COMMANDS</code></h3>
<p>The equivalent of LOCAL_SHORT_COMMANDS for your whole project. See the documentation for this variable in the <a href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk</a> section.</p>
<h3><code>NDK_TOOLCHAIN_VERSION</code></h3>
<p>Define this variable to either 4.8 or 4.9 to select version of the GCC compiler. 4.8 is the default for 32-bit ABIs, and 4.9 is the default for 64-bit ABIs.  To select version of Clang, define this variable to clang3.4, clang3.5 or clang (which chooses the most recent version of clang).</p>
<h3><code>APP_PIE</code></h3>
<p>Starting from Jelly Bean (4.1), Android's dynamic linker supports position-independent executables (PIE), which are built with <code>-fPIE</code>. This flag makes it harder to exploit memory corruption bugs by randomization the location of the code. By default, <code>ndk-build</code> will automatically set this value to '<code>true</code>' if your project targets <code>android-16</code> or higher. You may set it manually to either '<code>true</code>' or '<code>false</code>'.</p>
<p>IMPORTANT: PIE executables <em>cannot</em> run on Android releases prior to 4.1.</p>
<p>Note that this only applies to executables. It has no effect when building shared or static libraries.</p>
<h3><code>APP_THIN_ARCHIVE</code></h3>
<p>Sets the default value of LOCAL_THIN_ARCHIVE for all static library modules in this project. For more information, see the documentation for LOCAL_THIN_ARCHIVE in the <a href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk</a> section.</p>
<hr/>
<p> A trivial <code>Application.mk</code> file would be: </p>
<pre class="fragment">      -------------- cut here -------------------------
      APP_PROJECT_PATH := &lt;path to project&gt;
      -------------- cut here -------------------------</pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK Programmer&#39;s Guide by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
  </ul>
</div>
</body>
</html>
